Searches text on a character-by-character basis, replacing all instances of a string in that text with another string.

SInt16 ReplaceText (
    Handle baseText, 
    Handle substitutionText, 
    Str15 key
);

Parameter descriptions

baseText

A handle to the string in which ReplaceText is to substitute text.

substitutionText

A handle to the string that ReplaceText uses as substitute text.

key

A Pascal string of less than 16 bytes that ReplaceText searches for.

function result

An integer value; if positive, it indicates the number of substitutions performed; if negative, it indicates an error. The constant noErr is returned if there was no error and no substitutions were performed.

DISCUSSION

ReplaceText searches the text specified by the baseText parameter for instances of the string in the key parameter and replaces each instance with the text specified by the substitutionText parameter. ReplaceText searches on a character-by-character basis (as opposed to byte-by-byte), so it works properly for all script systems, including 2-byte script systems. It recognizes 2-byte characters in script systems that contain them and advances the search appropriately after encountering a 2-byte character.

SPECIAL CONSIDERATIONS

ReplaceText may move memory; your application should not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)